home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tk / selection.man < prev    next >
Encoding:
Text File  |  1992-08-24  |  8.1 KB  |  272 lines
  1. '\"
  2. '\" Copyright 1990 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/wish/man/RCS/selection.man,v 1.4 91/12/06 10:42:55 ouster Exp $ SPRITE (Berkeley)
  11. '/" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS selection cmds
  189. .BS
  190. '\" Note:  do not modify the .SH NAME line immediately below!
  191. .SH NAME
  192. selection \- Manipulate the X selection
  193. .SH SYNOPSIS
  194. \fBselection get \fR?\fItype\fR?
  195. .sp
  196. \fBselection handle \fIwindow command \fR?\fItype\fR? ?\fIformat\fR?
  197. .BE
  198.  
  199. .SH DESCRIPTION
  200. .PP
  201. This command provides a Tcl interface to the X selection mechanism and
  202. implements the full selection functionality described in the
  203. X Inter-Client Communication Conventions Manual (ICCCM), except that it
  204. supports only the primary selection.
  205. .PP
  206. The \fBselection get\fR form of the command retrieves the value
  207. of the primary selection and returns it as a result.
  208. \fBType\fR specifies the form in which the selection is to be
  209. returned (the desired ``target'' for conversion, in ICCCM
  210. terminology), and should be an
  211. atom name such as STRING or FILE_NAME;  see the Inter-Client
  212. Communication Conventions Manual for complete details.
  213. \fBType\fR defaults to STRING.  The selection owner may choose to
  214. return the selection in any of several different representation
  215. formats, such as STRING, ATOM, INTEGER, etc. (this format is
  216. different than the selection type;  see the ICCCM for all the
  217. confusing details).  If the selection is returned in
  218. a non-string format, such as INTEGER or ATOM, the \fBselection\fR
  219. command converts it to string format as a collection of fields
  220. separated by spaces:  atoms are converted to their
  221. textual names, and anything else is converted to hexadecimal
  222. integers.
  223. .PP
  224. The \fBselection handle\fR command creates a handler for selection requests:
  225. it arranges for \fIcommand\fR to be executed
  226. whenever the primary selection is
  227. owned by \fIwindow\fR and someone attempts to retrieve it in the form
  228. given by \fItype\fR (e.g. \fItype\fR is specified in the \fBselection get\fR
  229. command).  \fIType\fR defaults to STRING.
  230. .PP
  231. When the retrieval occurs, two additional numbers will be
  232. appended to \fIcommand\fR (with space separators), and the resulting
  233. string will be executed as a Tcl command.  The two additional numbers
  234. are \fIoffset\fR and \fImaxBytes\fR:  \fIoffset\fR specifies a starting
  235. character position in the selection and \fImaxBytes\fR gives the maximum
  236. number of bytes to retrieve.  The command should return a value consisting
  237. of at most \fImaxBytes\fR of the selection, starting at position
  238. \fIoffset\fR.  For very large selections (larger than \fImaxBytes\fR)
  239. the selection will be retrieved using several invocations of \fIcommand\fR
  240. with increasing \fIoffset\fR values.  If \fIcommand\fR returns a string
  241. whose length is less than \fImaxBytes\fR, the return value is assumed to
  242. include all of the remainder of the selection;  if the length of
  243. \fIcommand\fR's result is equal to \fImaxBytes\fR then
  244. \fIcommand\fR will be invoked again, until it eventually
  245. returns a result shorter than \fImaxBytes\fR.  The value of \fImaxBytes\fR
  246. will always be relatively large (thousands of bytes).
  247. .PP
  248. The \fIformat\fR argument specifies the representation that should be
  249. used to transmit the selection to the requester (the second column of
  250. Table 2 of the ICCCM), and defaults to STRING.  If \fIformat\fR is
  251. STRING, the selection is transmitted as 8-bit ASCII characters (i.e.
  252. just in the form returned by \fIcommand\fR).  If \fIformat\fR is
  253. ATOM, then the return value from \fIcommand\fR is divided into fields
  254. separated by white space;  each field is converted to its atom value,
  255. and the 32-bit atom value is transmitted instead of the atom name.
  256. For any other \fIformat\fR, the return value from \fIcommand\fR is
  257. divided into fields separated by white space and each field is
  258. converted to a 32-bit integer;  an array of integers is transmitted
  259. to the selection requester.
  260. .PP
  261. The \fIformat\fR argument is needed only for compatibility with
  262. selection requesters that don't use Tk.  If the Tk toolkit is being
  263. used to retrieve the selection then the value is converted back to
  264. a string at the requesting end, so \fIformat\fR is
  265. irrelevant.
  266. .PP
  267. If no handler has been declared for type TARGETS or type TIMESTAMP,
  268. Tk will automatically respond to selection requests for these types.
  269.  
  270. .SH KEYWORDS
  271. format, handler, ICCCM, selection, target, type
  272.